Setting Drawing Parameters16

The functions described in this section allow you to specify various parameters for drawing operations, such as clipping, scaling, graphics mode, and decompression quality. All of these functions are based on corresponding routines in the Image Compression Manager for working with image decompression sequences.

GraphicsImportSetBoundsRect

Defines the rectangle in which to draw an image.



 
pascal ComponentResult GraphicsImportSetBoundsRect (

                     GraphicsImportComponent ci,

                     const Rect *bounds);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
bounds: A pointer to a rectangle structure describing the bounding rectangle into which the image will be drawn.

DISCUSSION

You use this function to define the rectangle into which the graphics image should be drawn. The function creates a transformation matrix to map the image's natural bounds to the specified bounds and then calls the GraphicsImportSetMatrix function.

If the source rectangle is equal to the natural bounds, this function is equivalent to GraphicsImportSetDestRect . For more information on the relationship between rectangles and transformation matrix, see "Getting/Setting the Destination Rectangle" .

Because this function affects the transformation matrix, you should use the GraphicsImportSetMatrix function [link] instead of this function when you also need to specify more complex transformations of the matrix.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportGetBoundsRect

Returns the bounding rectangle for drawing.



 
pascal ComponentResult GraphicsImportGetBoundsRect (

                     GraphicsImportComponent ci,

                     Rect *bounds);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
bounds: A pointer to a rectangle structure describing the bounding rectangle that has been defined for the image.

DISCUSSION

This is a convenience function that is implemented by calling GraphicsImportGetMatrix [link] and GraphicsImportGetNaturalBounds [link] and using the results to calculate the drawing rectangle.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportSetMatrix

Defines the transformation matrix to use for drawing an image.



 
pascal ComponentResult GraphicsImportSetMatrix (

                     GraphicsImportComponent ci,

                     const MatrixRecord *matrix);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
matrix: A pointer to a matrix structure that specifies how to transform the image during decompression. For example, you can use a transformation matrix to scale or rotate the image. To set the matrix to identity, pass nil in this parameter.

DISCUSSION

The GraphicsImportSetMatrix function establishes the transformation matrix to be applied to an image, which determines where and how it will be drawn.

This function affects the bounding rectangle defined for the image. You can specify where an image will be drawn by setting either a transformation matrix or a bounding rectangle, but it is usually more convenient for applications to set a bounding rectangle using the GraphicsImportSetBoundsRect [link] function.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportGetMatrix

Returns the transformation matrix to be used for drawing.



 
pascal ComponentResult GraphicsImportGetMatrix (

                     GraphicsImportComponent ci,

                     MatrixRecord *matrix);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
matrix: A pointer to the transformation matrix that has been defined for the image.

DISCUSSION

The transformation matrix is initialized to the identity matrix when the graphics import component is instantiated.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportSetClip

Defines the clipping region for drawing.



 
pascal ComponentResult GraphicsImportSetClip (

                     GraphicsImportComponent ci,

                     RgnHandle clipRgn);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
clipRgn: A handle to a clipping region in the destination coordinate system. Set to nil to disable clipping. The graphics import component makes a copy of this region.

DISCUSSION

Because all drawing operations ignore the port clip, you must use this function to clip an image. The graphics importer component draws only that portion of the image that lies within the specified clipping region.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportGetClip

Returns the current clipping region.



 
pascal ComponentResult GraphicsImportGetClip (

                     GraphicsImportComponent ci,

                     RgnHandle *clipRgn);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
clipRgn: A handle to the clipping region that has been defined for the image. Returns nil if there is no clipping region.

DISCUSSION

The caller must dispose of the returned region handle.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportSetGraphicsMode

Sets the graphics transfer mode for an image.



 
pascal ComponentResult GraphicsImportSetGraphicsMode (

                     GraphicsImportComponent ci,

                     long graphicsMode,

                     const RGBColor *opColor);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
graphicsMode: Specifies the graphics transfer mode to use for drawing the image. QuickTime supports the same graphics modes as Color QuickDraw's CopyBits function (described in Inside Macintosh: Imaging with QuickDraw ) as well as any mode defined by the Image Compression manager, such as alpha modes.
opColor: A pointer to an RGB color structure describing the color to use for blending and transparent operations.

DISCUSSION

You can use this function to specify the graphics transfer mode and color to use for blending and transparent operations.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportGetGraphicsMode

Returns the graphics transfer mode for an image.



 
pascal ComponentResult GraphicsImportGetGraphicsMode (

                     GraphicsImportComponent ci,

                     long *graphicsMode,

                     RGBColor *opColor);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
graphicsMode: A pointer to a long integer. The function returns the QuickDraw graphics transfer mode setting for the image. Set to nil if you are not interested in this information.
opColor: A pointer to an RGB color structure. The function returns the color currently specified for blend and transparent operations. Set to nil if you are not interested in this information.

DISCUSSION

You can use this function to find out the current graphics transfer mode and color to use for blending and transparent operations. The default graphics mode is ditherCopy and the default opColor is 50% gray.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportSetQuality

Sets the image quality value.



 
pascal ComponentResult GraphicsImportSetQuality (

                     GraphicsImportComponent ci,

                     CodecQ quality);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
quality: Specifies the desired image quality for decompression. Values for this parameter are on the same scale as compression quality. See page 3-57 of Inside Macintosh: QuickTime for a description of the defined quality constants.

DISCUSSION

The quality parameter controls how precisely the decompressor decompresses the image data. Some decompressors may choose to ignore some image data to improve decompression speed.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportGetQuality

Returns the image quality value.



 
pascal ComponentResult GraphicsImportGetQuality (

                     GraphicsImportComponent ci,

                     CodecQ *quality);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
quality: A pointer to the currently specified quality value.

DISCUSSION

The quality value indicates how precisely the decompressor will decompress the image data. Some decompressors may choose to ignore some image data to improve decompression speed. With QuickTime 3 the default quality is codecHighQuality .

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportSetSourceRect

Sets the source rectangle to use for an image.



 
pascal ComponentResult GraphicsImportSetSourceRect (

                     GraphicsImportComponent ci,

                     const Rect *sourceRect);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
sourceRect: A pointer to a rectangle defining the portion of the image to decompress. This rectangle must lie within the boundary rectangle of the source image. Set to nil to use the entire image.

DISCUSSION

This function provides a way to use only a portion of the source image. Set the sourceRect parameter to nil to specify that the entire image source rectangle should be used.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportGetSourceRect

Returns the current source rectangle for an image.



 
pascal ComponentResult GraphicsImportGetSourceRect (

                     GraphicsImportComponent ci,

                     Rect *sourceRect);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
sourceRect: A pointer to a rectangle structure. The function returns the source rectangle currently specified for the image.

DISCUSSION

This function returns the current source rectangle, as specified by the GraphicsImportSetSourceRect function. The default source rectangle is the image's natural bounds.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportSetProgressProc

Installs a progress procedure to call while drawing an image.



 
pascal ComponentResult GraphicsImportSetProgressProc (

                     GraphicsImportComponent ci,

                     ICMProgressProcRecordPtr progressProc);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
progressProc: Points to a progress function structure. If you pass a value of -1, you obtain a standard progress function. If you want to remove the existing progress function, pass nil .

DISCUSSION

This function sets a progress function that will be installed in the image decompression sequence used to draw the image.

See the Movie Toolbox chapter of QuickTime 4 Reference for more information about progress functions.

If your progress function does any drawing, you should take care to set a safe graphics state before doing so, and to restore the graphics state afterwards. In particular, the current graphics device may be an offscreen device.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportGetProgressProc

Returns the current progress procedure.



 
pascal ComponentResult GraphicsImportGetProgressProc (

                     GraphicsImportComponent ci,

                     ICMProgressProcRecordPtr progressProc);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
progressProc: A pointer to a progress procedure structure.

DISCUSSION

By default, graphics import components have no progress procedure.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

Setting Drawing Parameters

GraphicsImportSetBoundsRect

DISCUSSION

RESULT CODES

GraphicsImportGetBoundsRect

DISCUSSION

RESULT CODES

GraphicsImportSetMatrix

DISCUSSION

RESULT CODES

SEE ALSO

GraphicsImportGetMatrix

DISCUSSION

RESULT CODES

GraphicsImportSetClip

DISCUSSION

RESULT CODES

GraphicsImportGetClip

DISCUSSION

RESULT CODES

GraphicsImportSetGraphicsMode

DISCUSSION

RESULT CODES

GraphicsImportGetGraphicsMode

DISCUSSION

RESULT CODES

GraphicsImportSetQuality

DISCUSSION

RESULT CODES

GraphicsImportGetQuality

DISCUSSION

RESULT CODES

GraphicsImportSetSourceRect

DISCUSSION

RESULT CODES

GraphicsImportGetSourceRect

DISCUSSION

RESULT CODES

GraphicsImportSetProgressProc

DISCUSSION

RESULT CODES

GraphicsImportGetProgressProc

DISCUSSION

RESULT CODES